SampleLib.cpp File Reference

---

Detailed Description

The sample shows how to implement an external object and to extend the JavaScript DOM, showing in particular how to use the object-oriented interface.

The sample demonstrates the two mechansisms for extending the JavaScript DOM, the direct interface and the indirect (object-oriented) interface.

Direct Interface:
This enables you to expose methods of your shared library as a method in the JavaScript environment. This allows you to pass simple data types back to JavaScript from the External Object such as Strings, booleans, integers and scripts.

For information on how to call the individual methods from JavaScript, see the comments for each methods or see the loadSampleLib.jsx script file that accompanies this sample.

Indirect Interface:
This enables you to create new classes of objects in JavaScript with properties and methods. Your Shared Library is called when these methods or properties are used in in JavaScript.

If you are working with an installed (Release) build of Adobe Bridge CS3, then we recommend you choose the Release configuration of the shared library when testing the SampleLib. You can modify the shared library (Debug or Release) that is loaded in the loadSampleLib.jsx file itself.

See the JavaScript Tools Guide for more information on the direct interface and indirect (object-oriented) interface.

See SoSharedLibDefs.h for error codes and return types

See SoCClient.h for the indirect (object-oriented) interface

See sampleprojects for information on how to build the library

See installing for information on how to install and use the library

Classes
struct	myData_s
Typedefs
typedef struct myData_s	myData_t
typedef myData_t *	myData_p
Functions
void *	unused (void *x)
SAMPLIB long	ESGetVersion ()
	Returns the version number of the library.
SAMPLIB char *	ESInitialize (TaggedData *argv, long argc)
	Initialize the library and return function signatures.
SAMPLIB void	ESTerminate ()
	Terminate the library.
SAMPLIB void	ESFreeMem (void *p)
	Free any string memory which has been returned as function result.
SAMPLIB void *	ESMallocMem (size_t nBytes)
	Allocate some memory.
SAMPLIB long	setVersion (TaggedData *argv, long argc, TaggedData *result)
	Change the version number by setting the global "version".
static char *	stringize (TaggedData *p)
	Helper function to "Stringize" each argument.
SAMPLIB long	createObject (TaggedData *argv, long argc, TaggedData *result)
	Example of a function that takes arguments with a known type (because there is a signature for it).
SAMPLIB long	createArray (TaggedData *argv, long argc, TaggedData *result)
SAMPLIB long	paramAny (TaggedData *argv, long argc, TaggedData *result)
	Example of a function that takes an argument of any type.
SAMPLIB long	paramBool (TaggedData *argv, long argc, TaggedData *result)
	Example of a function that takes a boolean argument.
SAMPLIB long	paramUInt32 (TaggedData *argv, long argc, TaggedData *result)
	Example of a function that takes an unsigned integer argument.
SAMPLIB long	paramInt32 (TaggedData *argv, long argc, TaggedData *result)
	Example of a function that takes a signed integer argument.
SAMPLIB long	paramFloat64 (TaggedData *argv, long argc, TaggedData *result)
	Example of a function that takes an 64 bit floating point argument.
SAMPLIB long	paramString (TaggedData *argv, long argc, TaggedData *result)
	Example of a function that takes a string argument.
SAMPLIB long	built (TaggedData *argv, long argc, TaggedData *result)
	Example of a function that returns a string.
ESerror_t	objectInitialize (SoHObject hObject, int argc, TaggedData *argv)
	Called whenever a ne object is constructed.
ESerror_t	objectGet (SoHObject hObject, SoCClientName *name, TaggedData *pResult)
	Retrieves the value of a property of this object.
ESerror_t	objectPut (SoHObject hObject, SoCClientName *name, TaggedData *pValue)
	Sets a value of a property of this object.
ESerror_t	objectCall (SoHObject hObject, SoCClientName *name, int argc, TaggedData *argv, TaggedData *pResult)
	Calls a method of this object.
ESerror_t	objectToString (SoHObject hObject, TaggedData *pResult)
	Not used in this sample.
ESerror_t	objectValueOf (SoHObject hObject, TaggedData *pResult)
	Not used in this sample.
ESerror_t	objectFinalize (SoHObject hObject)
	Calls when the object is released from memory.
SAMPLIB int	ESClientInterface (SoCClient_e kReason, SoServerInterface *pServer, SoHServer hServer)
Variables
static long	libraryVersionNumber = 1
	This is the version number, and can be modified by setVersion().
static char *	signatures
	String string that contains the signatures of every ESFunction defined here, used to support the JavaScript reflection interface.
SoObjectInterface *	gpObjectInterface = NULL
	Array of function pointers to communiate use of the new class.
SoServerInterface *	gpServer = NULL
	Structure of function pointers which enable the client to call JavaScript.
SoHServer	ghServer = NULL
	The server object.
int	ME = 0
	Counter for instances created.
SoObjectInterface	objectInterface
	Array of SoObjectInterface.

---

Typedef Documentation

typedef myData_t* myData_p

typedef struct myData_s myData_t

---

Function Documentation

SAMPLIB long built	(	TaggedData *	argv,
		long	argc,
		TaggedData *	result
	)

Example of a function that returns a string.

If memory has not been allocated correctly then returns an out of memory error.

Parameters:

	argv	- The JavaScript argument
	argc	the argument count
	result	The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::string, TaggedData_s::type, and unused().

Referenced by objectGet().

SAMPLIB long createArray	(	TaggedData *	argv,
		long	argc,
		TaggedData *	result
	)

References TaggedData_s::data, TaggedData_s::string, stringize(), and TaggedData_s::type.

SAMPLIB long createObject	(	TaggedData *	argv,
		long	argc,
		TaggedData *	result
	)

Example of a function that takes arguments with a known type (because there is a signature for it).

Returns a script that creates a small JavaScript object containing one property. Argument 1 contains the name of the property, argument 2 contains the value. Return a script that creates an object: "({ 'name':'value' })".

If the arguments are not correct then a bad argument error code is returned.

Parameters:

	argv	- The JavaScript argument
	argc	the argument count
	result	The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::string, stringize(), and TaggedData_s::type.

SAMPLIB int ESClientInterface	(	SoCClient_e	kReason,
		SoServerInterface *	pServer,
		SoHServer	hServer
	)

References SoServerInterface_s::addClass, ghServer, kSoCClient_init, kSoCClient_term, and ME.

SAMPLIB void ESFreeMem

(

void *

p

)

Free any string memory which has been returned as function result.

JavaScipt calls this function to release the memory associated with the string. Used for the direct interface.

Parameters:

*p

Pointer to the string

SAMPLIB long ESGetVersion

(

)

Returns the version number of the library.

ExtendScript publishes this number as the version property of the object created by new ExternalObject. Used by the direct interface.

References libraryVersionNumber.

SAMPLIB char* ESInitialize	(	TaggedData *	argv,
		long	argc
	)

Initialize the library and return function signatures.

These signatures have no effect on the arguments that can be passed to the functions. They are used by JavaScript to cast the arguments, and to populate the reflection interface.

References signatures, and unused().

SAMPLIB void* ESMallocMem

(

size_t

nBytes

)

Allocate some memory.

Used for the object interface.

Parameters:

nBytes

The amount of space to allocate

Returns:

Pointer to the allocated space

SAMPLIB void ESTerminate

(

)

Terminate the library.

Does any necessary clean up that is needed.

ESerror_t objectCall	(	SoHObject	hObject,
		SoCClientName *	name,
		int	argc,
		TaggedData *	argv,
		TaggedData *	pResult
	)

Calls a method of this object.

Parameters:

	hObject	- The reference for this instance
	name	- The name of the method to call
	argv	- The JavaScript argument
	argc	- The argument count
	pResult	- The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::fltval, TaggedData_s::intval, SoCClientName_s::name_sig, TaggedData_s::string, TaggedData_s::type, and unused().

ESerror_t objectFinalize

(

SoHObject

hObject

)

Calls when the object is released from memory.

Parameters:

hObject

- The reference for this instance

References SoServerInterface_s::getClientData, and SoServerInterface_s::setClientData.

ESerror_t objectGet	(	SoHObject	hObject,
		SoCClientName *	name,
		TaggedData *	pResult
	)

Retrieves the value of a property of this object.

Parameters:

	hObject	- The reference for this instance
	name	- The name of the property
	pResult	- Pointer to the result being returned to JavaScript

References built(), TaggedData_s::data, TaggedData_s::fltval, SoServerInterface_s::getClientData, TaggedData_s::intval, SoCClientName_s::name_sig, TaggedData_s::string, and TaggedData_s::type.

ESerror_t objectInitialize	(	SoHObject	hObject,
		int	argc,
		TaggedData *	argv
	)

Called whenever a ne object is constructed.

    var myObj = new SampleObject(param1);

Parameters:

	hObject	- The reference for this instance
	argc	- The argument count
	argv	- The arguments passed in the constructor

References myData_s::a, SoServerInterface_s::addMethods, SoServerInterface_s::addProperties, myData_s::b, ME, myData_s::me, SoServerInterface_s::setClientData, SoServerInterface_s::taggedDataInit, and unused().

ESerror_t objectPut	(	SoHObject	hObject,
		SoCClientName *	name,
		TaggedData *	pValue
	)

Sets a value of a property of this object.

Parameters:

	hObject	- The reference for this instance
	name	- The name of the property to update
	pValue	- A pointer to the value to write to the property

References TaggedData_s::data, SoServerInterface_s::getClientData, SoCClientName_s::name_sig, and TaggedData_s::string.

ESerror_t objectToString	(	SoHObject	hObject,
		TaggedData *	pResult
	)

Not used in this sample.

To implement, change from NULL to objectToString in array of SoObjectInterface.

See also:

objectInterface

References TaggedData_s::data, SoServerInterface_s::getClientData, TaggedData_s::string, and TaggedData_s::type.

ESerror_t objectValueOf	(	SoHObject	hObject,
		TaggedData *	pResult
	)

Not used in this sample.

To implement, change from NULL to objectToString in array of SoObjectInterface.

See also:

objectInterface

References TaggedData_s::data, SoServerInterface_s::getClientData, TaggedData_s::string, and TaggedData_s::type.

SAMPLIB long paramAny	(	TaggedData *	argv,
		long	argc,
		TaggedData *	result
	)

Example of a function that takes an argument of any type.

If the arguments are not correct then a bad argument error code is returned.

Parameters:

	argv	- The JavaScript argument
	argc	- the argument count
	result	- The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::fltval, TaggedData_s::intval, TaggedData_s::string, and TaggedData_s::type.

SAMPLIB long paramBool	(	TaggedData *	argv,
		long	argc,
		TaggedData *	result
	)

Example of a function that takes a boolean argument.

If the arguments are not correct then a bad argument error code is returned.

Parameters:

	argv	- The JavaScript argument
	argc	the argument count
	result	- The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::intval, and TaggedData_s::type.

SAMPLIB long paramFloat64	(	TaggedData *	argv,
		long	argc,
		TaggedData *	result
	)

Example of a function that takes an 64 bit floating point argument.

If the correct number of argument are not passed then a bad argument error code is returned. If the argument is not of the correct type then a data mismatch error is returned.

Parameters:

	argv	- The JavaScript argument
	argc	the argument count
	result	- The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::fltval, and TaggedData_s::type.

SAMPLIB long paramInt32	(	TaggedData *	argv,
		long	argc,
		TaggedData *	result
	)

Example of a function that takes a signed integer argument.

If the correct number of argument are not passed then a bad argument error code is returned. If the argument is not of the correct type then a data mismatch error is returned.

Parameters:

	argv	- The JavaScript argument
	argc	- The argument count
	result	- The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::intval, and TaggedData_s::type.

SAMPLIB long paramString	(	TaggedData *	argv,
		long	argc,
		TaggedData *	result
	)

Example of a function that takes a string argument.

If the correct number of argument are not passed then a bad argument error code is returned. If the argument is not of the correct type then a data mismatch error is returned. If memory has not been allocated correctly then returns an out of memory error.

Parameters:

	argv	- The JavaScript argument
	argc	the argument count
	result	- The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::string, and TaggedData_s::type.

SAMPLIB long paramUInt32	(	TaggedData *	argv,
		long	argc,
		TaggedData *	result
	)

Example of a function that takes an unsigned integer argument.

If the correct number of argument are not passed then a bad argument error code is returned. If the argument is not of the correct type then a data mismatch error is returned.

Parameters:

	argv	- The JavaScript argument
	argc	the argument count
	result	- The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::intval, and TaggedData_s::type.

SAMPLIB long setVersion	(	TaggedData *	argv,
		long	argc,
		TaggedData *	result
	)

Change the version number by setting the global "version".

 myObj.setVersion(2);

Parameters:

	argv	- The JavaScript argument
	argc	the argument count
	result	- The return value to be passed back to JavaScript

References TaggedData_s::data, TaggedData_s::intval, and libraryVersionNumber.

static char* stringize

(

TaggedData *

p

)

[static]

Helper function to "Stringize" each argument.

If the argument is not a string, convert it to a string. If it is a string, escape all quotes in the string with a backslash and quote the entire string.

Parameters:

p

Pointer to a TaggedData

Returns:

Return a dynamic buffer containing the string.

References TaggedData_s::data, TaggedData_s::intval, TaggedData_s::string, and TaggedData_s::type.

Referenced by createArray(), and createObject().

void* unused

(

void *

x

)

Referenced by built(), ESInitialize(), objectCall(), and objectInitialize().

---

Variable Documentation

SoHServer ghServer = NULL

The server object.

Referenced by ESClientInterface().

SoObjectInterface* gpObjectInterface = NULL

Array of function pointers to communiate use of the new class.

SoServerInterface* gpServer = NULL

Structure of function pointers which enable the client to call JavaScript.

long libraryVersionNumber = 1 [static]

This is the version number, and can be modified by setVersion().

Referenced by ESGetVersion(), and setVersion().

int ME = 0

Counter for instances created.

Referenced by ESClientInterface(), and objectInitialize().

SoObjectInterface objectInterface

Initial value:

{  objectInitialize
,  objectPut
,  objectGet
,  objectCall
,  NULL  
,  NULL  
,  objectFinalize
}

Array of SoObjectInterface.

Provides the interface which is used by JavaScript to communicate the use of the object

char* signatures [static]

Initial value:

    "setVersion_d,"         
    "createObject_ss,"  
    "createArray,"          
    "paramAny_a,"               
    "paramString_s,"        
    "paramBool_b,"          
    "paramUInt32_u,"        
    "paramInt32_d,"         
    "paramFloat64_f"        
    "built"

String string that contains the signatures of every ESFunction defined here, used to support the JavaScript reflection interface.

Note that this is a single comma-separated values string, concatenated by the compiler.

Referenced by ESInitialize().